Golang SDK

Golang SDK 使用说明

在使用前，请先阅读基础知识 的介绍。

集成卓尔分析 SDK

在 Golang 代码中集成卓尔分析 SDK，使用卓尔分析采集并分析用户数据。

我们推荐 Golang 官方工具管理 Golang 项目并获取卓尔分析 SDK：

go get github.com/zalldata/za-sdk-go

或更新本地已经存在的sdk:

go get -u github.com/zalldata/za-sdk-go

也可以从 GitHub 下载卓尔分析 SDK 的源代码。

SDK 需要 Golang 1.6 以上，不依赖第三方库。目前 Golang SDK 不支持 Windows。

初始化卓尔分析 SDK

首先从卓尔分析的主页中，获取数据接收的 URL 和 Token。

如果使用卓尔分析服务，需获取的配置信息为:

数据接收地址：http://{$service_name}.zalldata.cn/a?project={$project_name}&service={$service_name}&token={$project_token}

在程序中初始化 SDK

在程序中初始化的代码段中构造卓尔分析 SDK 的实例：

import sdk "github.com/zalldata/za-sdk-go"

// 从卓尔分析配置页面中获取数据接收的 URL
ZA_SERVER_URL := "YOUR_SERVER_URL"

// 初始化一个 Consumer，用于数据发送
// DefaultConsumer 是同步发送数据，因此不要在任何线上的服务中使用此 Consumer
consumer, err := sdk.InitDefaultConsumer(ZA_SERVER_URL, 10000)
//...
// 使用 Consumer 来构造 ZallAnalytics 对象
za:= sdk.InitZallAnalytics(consumer, "default", false)
defer za.Close()

properties := map[string]interface{}{
        "price": 12,
        "name": "apple",
}

// 记录用户事件
err = za.Track("ABCDEFG1234567", "ViewProduct", properties, false)

其中 YOUR_SERVER_URL 是前文中从卓尔分析获取的数据接收的 URL。用户程序应该一直持有该实例，直到程序结束。程序退出前，需要使用 Close() 方法显式关闭，否则可能丢失部分缓存的数据。

使用卓尔分析时，引入卓尔分析 SDK 后首先初始化一个 consumer，接着初始化卓尔分析对象。

初始化卓尔分析对象的接口为：

// c 为 consumer，projectName 为项目名，timeFree 为是否导入历史数据
// 默认情况下，卓尔会过滤发生时间比较久远数据（例如 10 天之前，具体取决于服务端设置），如果想导入历史数据，可以通过开启 timeFree 选项来绕过这个限制。
func InitZallAnalytics(c consumers.Consumer, projectName string, timeFree bool) ZallAnalytics

示例

za:= sdk.InitZallAnalytics(consumer, "default", false)
// 退出函数前调用 Close，回收资源，发送缓存中的数据
defer za.Close()
// ...

至此，我们已经可以正常使用卓尔分析 SDK 了。需了解更多关于 SDK 的使用方法，可以跳到本文末尾的控制卓尔分析 SDK 一节。

追踪事件

第一次接入卓尔分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验卓尔分析的分析功能。例如：

图片社交产品，可以追踪用户浏览图片和评论事件
电商产品，可以追踪用户注册、浏览商品和下订单等事件

用户通过 Track() 接口记录事件，对于任何事件，必须包含用户标志符（Distinct ID）和事件名（event）两个参数。用户可以在 Track() 的第三个参数传入一个 map[string]interface{} 对象，为事件添加自定义事件属性。以电商产品为例，可以这样追踪一次购物行为：

接口

// distinctId 是用户标识，event 是事件名，properties 是自定义事件属性，isLoginId 表示是否登录
func (za*ZallAnalytics) Track(distinctId, event string, properties map[string]interface{}, isLoginId bool) error

示例

distinct_id := "ABCDEF123456"

properties := map[string]interface{}{
    // "$time" 属性是系统预置属性，取值为 int64 类型，表示事件发生的时间，如果设置该属性，则替换 SDK 内部获取的系统当前时间。如果不填入该属性，则默认使用系统当前时间
    "$time" : time.Now().Unix(),
    // "$ip" 属性是系统预置属性，如果服务端中能获取用户 IP 地址，并填入该属性，卓尔分析会自动根据 IP 地址解析用户的省份、城市信息
    "$ip" : "123.123.123.123",
    // 商品 ID
    "ProductId" : "123456",
    // 商品类别
    "ProductCatalog" : "Laptop Computer",
    // 是否加入收藏夹，Boolean 类型的属性
    "IsAddedToFav" : True,
}

// 记录用户浏览商品事件
err := za.Track(distinct_id, "ViewProduct", properties, true)

properties:= map[string]interface{}{
    // 用户 IP 地址
    "$ip" : "123.123.123.123",
    // 商品 ID 列表，[]string 类型的属性
    "ProductIdList" : []string{"123456", "234567", "345678"},
    // 订单价格
    "OrderPaid" : 12.10,
}

// 记录用户订单付款事件
err = za.Track(distinct_id, "PaidOrder", properties, true)

事件属性

如前文中的样例，追踪的事件可以设置自定义的事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，卓尔分析有一些约束:

事件属性是一个 map[string]interface{} 对象
map 中每个元素描述一个属性，Key 为属性名称，必需是 string 类型
map 中，每个元素的 Value 是属性的值，支持 string、int、float64、[]string、time.Time

对于卓尔分析中事件属性的更多约束，请参考数据格式

系统预置属性

如前文中样例，事件属性中以 "$" 开头的属性为系统预置属性，在自定义事件属性中填入对应 "$" 开头的属性值可以覆盖这些预置属性：

$ip - 填入该属性，卓尔分析会自动根据 IP 地址解析用户的省份、城市信息，该属性值为 string 类型；
$time - 填入该属性，卓尔分析将事件时间设置为属性值的时间，该属性值取值为 int64 类型。请注意，卓尔分析默认会过滤忽略 365 天前或 3 天后的数据，如需修改请联系我们。

关于其他更多预置属性，请参考数据格式中 "预置属性" 一节。

事件公共属性

特别地，如果某个事件的属性，在所有事件中都会出现，可以通过 RegisterSuperProperties() 将该属性设置为事件公共属性。例如将服务器的应用版本及机房地址设置为事件的公共属性，示例如下:

    superProperty := map[string]interface{}{
        "ServerVersion": "1.2",
        "Location":      "BeiJing",
    }
    za.RegisterSuperProperties(superProperty)

使用 ClearSuperProperties*() 会删除所有已设置的事件公共属性。使用 UnregisterSuperProperty()* 会删除指定 Key 的公共属性。

当事件公共属性和事件属性的 Key 冲突时，事件属性优先级最高，它会覆盖事件公共属性。

用户识别

在服务端应用中，卓尔分析也要求为每个事件设置用户的 Distinct ID，这有助于卓尔分析提供更准确的留存率等数据。

对于注册用户，推荐使用系统中的用户 ID 作为 Distinct ID，不建议使用用户名、Email、手机号码等可以被修改的信息。

所有的 Track 和 Profile 系列方法建议明确指定 isLoginId 参数，以便明确告知卓尔分析用户 ID 的类型。

用户注册/登录

当同一个用户的 Distinct ID 发生变化时（一般情况为匿名用户注册行为），可以通过 TrackSignup() 将旧的 Distinct ID 和新的 Distinct ID 关联，以保证用户分析的准确性。

接口

// distinctId 为新的 ID（注册后的 ID），originId 为旧 ID（匿名 ID）
func (za*ZallAnalytics) TrackSignup(distinctId, originId string) error

示例

// 匿名 ID 由前端传过来
anonymous_id := "9771C579-71F0-4650-8EE8-8999FA717761"

register_id := "0012345678"
// 用户注册/登录时，将用户注册 ID 与 匿名 ID 关联
err := za.TrackSignup(register_id, anonymous_id)

注意，对同一个用户，TrackSignup() 一般情况下建议只调用一次（通常在用户注册时调用），用户登录前后的行为的关联建议在业务端实现。在卓尔分析 1.13 版本之前，多次调用 TrackSignup() 时，只有第一次关联行为是有效的。卓尔分析 1.13 版本之后提供了多设备 ID 关联的方法。更详细的说明请参考标识用户，并在必要时联系我们的技术支持人员。

设置用户属性

为了更准确地提供针对人群的分析服务，卓尔分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为过滤条件或以用户属性作为维度进行多维分析。

记录用户属性

使用 ProfileSet() 设置用户属性:
接口

// distinctId 为用户标识，properties 为要设置的用户属性，isLoginId 标示 distinctId 是否为登录后的 ID
func (za*ZallAnalytics) ProfileSet(distinctId string, properties map[string]interface{}, isLoginId bool) error

示例

distinct_id := "ABCDEF123456789"

properties := map[string]interface{}{
    // 用户性别属性（Sex）为男性
    "Sex" : "Male",
    // 用户等级属性（Level）为 VIP
    "UserLevel" : "Elite VIP",
}

// 设置用户属性
err := za.ProfileSet(distinct_id, properties, true)

对于不再需要的用户属性，可以通过 ProfileUnset() 接口将属性删除。

用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考数据格式。

记录初次设定的属性

对于只在首次设置时有效的属性，我们可以使用 ProfileSetOnce() 记录这些属性。与 ProfileSet() 接口不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。因此，ProfileSetOnce() 比较适用于为用户设置首次激活时间、首次注册时间等属性。

接口

// distinctId 为用户标识，properties 为要设置的用户属性，isLoginId 标示 distinctId 是否为登录后的 ID
func (za*ZallAnalytics) ProfileSetOnce(distinctId string, properties map[string]interface{}, isLoginId bool) error

示例

distinct_id := "ABCDEF123456789"

// 设置用户渠道属性（AdSource）为 "App Store"
properties := map[string]interface{}{
    "AdSource" : "App Store",
}
err := za.ProfileSetOnce(distinct_id, properties, true)

properties = map[string]interface{}{
    "AdSource" : "Search Engine",
}
// 再次设置用户渠道属性（AdSource），设定无效，属性 "AdSource" 的值仍为 "App Store"
err = za.ProfileSetOnce(distinct_id, properties, true)

数值类型的属性

对于数值型的用户属性，可以使用 ProfileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。

接口

// distinctId 为用户标识，properties 为要设置的用户属性，这个属性中应该只包含 value 为 int 的属性，isLoginId 标示 distinctId 是否为登录后的 ID
func (za*ZallAnalytics) ProfileIncrement(distinctId string, properties map[string]interface{}, isLoginId bool) error

示例

distinct_id := "ABCDEF123456789"

properties := map[string]interface{}{
    "GamePlayed" : 1,
}
// 设置用户游戏次数属性（GamePlayed），将次数累加1次
err := za.ProfileIncrement(distinct_id, properties, true)

列表类型的属性

接口

// distinctId 为用户标识，properties 为要设置的用户属性，这个属性中应该只包含 value 为 [string] 的属性，isLoginId 标示 distinctId 是否为登录后的 ID
func (za*ZallAnalytics) ProfileAppend(distinctId string, properties map[string]interface{}, isLoginId bool) error

示例

distinct_id := "ABCDEF123456789"

properties := map[string]interface{}{
    // 电影列表
    "Movies" : []string{"Sicario", "Love Letter"},
    // 游戏列表
    "Games" : []string{"Call of Duty", "Halo"},
}

// 传入properties，设置用户喜欢的电影属性（movies）和喜欢的游戏属性（games）
// 设置成功后，"Movies" 属性值为 ["Sicario", "Love Letter"]；"Games" 属性值为 ["Call of Duty", "Halo"]
err := za.ProfileAppend(distinct_id, properties, true)

// 传入属性名称和需要插入属性的值，设置用户喜欢的电影属性（Movies）
// 设置成功后 "Movies" 属性值为 ["Sicario", "Love Letter", "Dead Poets Society"]
properties = map[string]interface{}{
    "Movies" : []string{"Dead Poets Society"},
}
err = za.ProfileAppend(distinct_id, properties, true)

// 传入属性名称和需要插入属性的值，设置用户喜欢的电影属性（Movies），
// 但属性值 "Love Letter" 与已列表中已有元素重复，操作无效，
// "Movies" 属性值仍然为 ["Sicario", "Love Letter", "Dead Poets Society"]
properties = map[string]interface{}{
    "Movies" : []string{"Love Letter"},
}
err = za.ProfileAppend(distinct_id, properties, true)

物品元数据上报

在卓尔推荐项目中，客户需要将物品元数据上报，以开展后续推荐业务的开发与维护。卓尔分析 SDK 提供了设置与删除物品元数据的方法。

item_id（物品 ID ）与 item_type （物品所属类型）共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个参数，来完成对物品的操作。

设置物品

直接设置一个物品，如果已存在则覆盖。除物品 ID 与物品所属类型外，其他物品属性需在 $properties 中定义。

物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考数据格式。

// 示例
itemType := "apple"
itemId := "12345"
err = za.ItemSet(itemType, itemId, map[string]interface{}{"price": "3",})

删除一个物品

如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。

除物品 ID 与物品所属类型外，不解析其他物品属性。

// 示例
itemType := "apple"
itemId := "12345"
err = za.ItemDelete(itemType, itemId)

设置卓尔分析 SDK

Golang SDK 主要由以下两个组件构成:

ZallAnalytics：用于发送数据的接口对象，构造函数需要传入一个 Consumer 实例
Consumer：Consumer 会进行实际的数据发送

为了让开发者更灵活的接入数据，卓尔分析 SDK 实现了以下 Consumer：

LoggingConsumer
ConcurrentLoggingConsumer
DebugConsumer
DefaultConsumer
BatchConsumer

LoggingConsumer

用于将数据输出到指定目录并按天切割文件，支持通过参数指定是否按小时切割，一般用来处理实时数据，生成日志文件

初始化接口

// filename 为输出文件前缀，hourRotate 为是否按小时切割
func InitLoggingConsumer(filename string, hourRotate bool) (*consumers.LoggingConsumer, error)

例子

import sdk "github.com/zalldata/za-sdk-go"

// 初始化 LoggingConsumer
consumer, err := sdk.InitLoggingConsumer("/data/za/access.log", false)
// ...
// 使用 Consumer 来构造 ZallAnalytics 对象
za:= sdk.InitZallAnalytics(consumer, "default", false)
defer za.Close()

// ...

LoggingConsumer 的第一个参数是保存文件前缀，第二个参数表示是否启用按小时切割，默认是每天 0 点切割保留所有文件。

按小时切割关闭的情况下，文件将保存在以 prefix.YYYY-MM-DD（例如：假设 prefix 为 /data/za/access.log，当天是 2018-04-13，则输出文件为 /data/za/access.log.2018-03-13）
按小时切割开启的情况下，在小时整点切割，文件将保存在以 prefix.YYYY-MM-DD.H（例如：假设 prefix 为 /data/za/access.log，当天是 2018-04-13 14 点，则输出文件为 /data/za/access.log.2018-03-13.14）

// 按小时切分
consumer, err := sdk.InitLoggingConsumer("/data/za/access.log", true)

注意，请不要使用多进程写入同一个日志文件，可能会造成数据丢失或者错乱。如果需要多进程写入，请使用 ConcurrentLoggingConsumer。

ConcurrentLoggingConsumer

用于将数据输出到指定目录，并自动按天切割文件，支持按小时切割，参数含义同 LoggingConsumer ，与 LoggongConsumer 不同的是，它支持多进程写入同一个文件。

初始化接口

// filename 为输出文件前缀，hourRotate 为是否按小时切割
func InitConcurrentLoggingConsumer(filename string, hourRotate bool) (*consumers.ConcurrentLoggingConsumer, error)

例子

import sdk "github.com/zalldata/za-sdk-go"

// 初始化 ConcurrentLoggingConsumer
consumer, err := sdk.InitConcurrentLoggingConsumer("/data/za/access.log", true)
// ...
// 使用 Consumer 来构造 ZallAnalytics 对象
za:= sdk.InitZallAnalytics(consumer, "default", false)

// 程序结束前调用 Close() ，让 Consumer 刷新所有缓存数据到文件中
defer za.Close()

// ...

注意： LogAgent 配置文件中一定要注释掉 real_time_file_name 参数，否则无法正常导入数据。已使用 LoggingConsumer 的客户建议按照如下步骤切换到 ConcurrentLoggingConsumer：

第 1 步停掉 LogAgent，并注释掉 LogAgent 配置中的 real_time_file_name 参数。
第 2 步将日志目录下的 real_time_file_name 的文件加上当前时间的后缀 ".YYYY-MM-DD"。
第 3 步后端程序升级切换到 ConcurrentLoggingConsumer。
第 4 步重新启动 LogAgent。

DebugConsumer（测试使用)

用于校验数据导入是否正确，关于 Debug 模式的详细信息，请进入相关页面查看。请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用 Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。

初始化接口为

// url是接收端url，writeData表示是否校验数据，timeout是发送超时时间，单位是毫秒
// writeData为
//   true - 校验数据，并将数据导入到卓尔分析中
//   false - 校验数据，但不进行数据导入
func InitDebugConsumer(url string, writeData bool, timeout int) (*consumers.DebugConsumer, error)

例子

import sdk "github.com/zalldata/za-sdk-go"

// 卓尔分析数据接收的 URL
ZA_SERVER_URL := "YOUR_SERVER_URL"
// 发送数据的超时时间，单位毫秒
ZA_REQUEST_TIMEOUT := 100000
// Debug 模式下，是否将数据导入卓尔分析
//   true - 校验数据，并将数据导入到卓尔分析中
//   false - 校验数据，但不进行数据导入
ZA_DEBUG_WRITE_DATA := true

// 初始化 Debug Consumer
consumer, err := sdk.InitDebugConsumer(ZA_SERVER_URL, ZA_DEBUG_WRITE_DATA, ZA_REQUEST_TIMEOUT)
// ...
// 使用 Consumer 来构造 ZallAnalytics 对象
za:= sdk.InitZallAnalytics(consumer, "default", false)
defer za.Close()

// ...

通常用于导入小规模历史数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在任何线上服务中。普通 Consumer，实现，逐条、同步的发送数据给接收服务器。

初始化接口

// url 是接收端 URL，timeout 是发送超时时间，单位是毫秒
func InitDefaultConsumer(url string, timeout int) (*consumers.DefaultConsumer, error)

例子

import sdk "github.com/zalldata/za-sdk-go"

// 卓尔分析数据接收的 URL
ZA_SERVER_URL := "YOUR_SERVER_URL"
// 发送数据的超时时间，单位毫秒
ZA_REQUEST_TIMEOUT := 100000

// 初始化 Default Consumer
consumer, err := sdk.InitDefaultConsumer(ZA_SERVER_URL, ZA_REQUEST_TIMEOUT)
// ...
// 使用 Consumer 来构造 ZallAnalytics 对象
za:= sdk.InitZallAnalytics(consumer, "default", false)
defer za.Close()

// ...

BatchConsumer

通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在任何线上服务中。批量发送数据的 Consumer，当且仅当数据达到指定的量时，才将数据进行发送。

初始化接口

// url是接收端url，max是最大缓存条数，timeout是发送超时时间，单位是毫秒
func InitBatchConsumer(url string, max, timeout int) (*consumers.BatchConsumer, error)

例子

import sdk "github.com/zalldata/za-sdk-go"

// 卓尔分析数据接收的 URL
ZA_SERVER_URL := "YOUR_SERVER_URL"
// 发送数据的超时时间，单位毫秒
ZA_REQUEST_TIMEOUT := 100000
// 当缓存的数据量达到参数值时，批量发送数据
ZA_BULK_SIZE := 100

// 初始化 Batch Consumer
consumer, err := sdk.InitBatchConsumer(ZA_SERVER_URL, ZA_BULK_SIZE, ZA_REQUEST_TIMEOUT)
// ...
// 使用 Consumer 来构造 ZallAnalytics 对象
za:= sdk.InitZallAnalytics(consumer, "default", false)
defer za.Close()

// ...

注：本文档内容为卓尔产品使用和技术细节说明文档，不包含适销类条款；具体企业采购产品和技术服务内容，以商业采购合同为准。

Golang SDK

Golang SDK

Golang SDK 使用说明

集成卓尔分析 SDK

初始化卓尔分析 SDK

在程序中初始化 SDK

追踪事件

事件属性

系统预置属性

事件公共属性

用户识别

用户注册/登录

设置用户属性

记录用户属性

记录初次设定的属性

数值类型的属性

列表类型的属性

物品元数据上报

设置物品

删除一个物品

设置卓尔分析 SDK

LoggingConsumer

ConcurrentLoggingConsumer

DebugConsumer（测试使用)

BatchConsumer

results matching ""

No results matching ""